<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->

<B><A HREF="GETDIRENTRIES.html">GETDIRENTRIES(2)</A></B>	  FreeBSD System Calls Manual	      <B><A HREF="GETDIRENTRIES.html">GETDIRENTRIES(2)</A></B>


</PRE>
<H2>NAME</H2><PRE>
     <B>getdirentries</B> - get directory entries in a filesystem independent format


</PRE>
<H2>SYNOPSIS</H2><PRE>
     <B>#include</B> <B>&lt;sys/types.h&gt;</B>
     <B>#include</B> <B>&lt;dirent.h&gt;</B>

     <I>int</I>
     <B>getdirentries</B>(<I>int</I> <I>fd</I>, <I>char</I> <I>*buf</I>, <I>int</I> <I>nbytes</I>, <I>long</I> <I>*basep</I>)


</PRE>
<H2>DESCRIPTION</H2><PRE>
     <B>Getdirentries</B>() reads directory entries from the directory referenced by
     the file descriptor <I>fd</I> into the buffer pointed to by <I>buf</I>, in a filesystem
     independent format.  Up to <I>nbytes</I> of data will be transferred.  <I>Nbytes</I>
     must be greater than or equal to the block size associated with the file,
     see <B><A HREF="stat.html">stat(2)</A></B>.  Some filesystems may not support <B>getdirentries</B>() with
     buffers smaller than this size.

     The data in the buffer is a series of <I>dirent</I> structures each containing
     the following entries:

	   u_int32_t d_fileno;
	   u_int16_t d_reclen;
	   u_int8_t  d_type;
	   u_int8_t  d_namlen;
	   char    d_name[MAXNAMELEN + 1]; /* see below */

     The <I>d</I><B>_</B><I>fileno</I> entry is a number which is unique for each distinct file in
     the filesystem.  Files that are linked by hard links (see <B><A HREF="link.html">link(2)</A></B>)  have
     the same <I>d</I><B>_</B><I>fileno</I>. The <I>d</I><B>_</B><I>reclen</I> entry is the length, in bytes, of the di-
     rectory record.  The <I>d</I><B>_</B><I>type</I> entry is the type of the file pointed to by
     the directory record.  The file type values are defined in
     <I>&lt;sys/dirent.h&gt;</I>. The <I>d</I><B>_</B><I>name</I> entry contains a null terminated file name.
     The <I>d</I><B>_</B><I>namlen</I> entry specifies the length of the file name excluding the
     null byte.  Thus the actual size of <I>d</I><B>_</B><I>name</I> may vary from 1 to MAXNAMELEN
     + 1.

     Entries may be separated by extra space.  The <I>d</I><B>_</B><I>reclen</I> entry may be used
     as an offset from the start of a <I>dirent</I> structure to the next structure,
     if any.

     The actual number of bytes transferred is returned.  The current position
     pointer associated with <I>fd</I> is set to point to the next block of entries.
     The pointer may not advance by the number of bytes returned by
     <B>getdirentries</B>().  A value of zero is returned when the end of the direc-
     tory has been reached.

     <B>Getdirentries</B>() writes the position of the block read into the location
     pointed to by <I>basep</I>. Alternatively, the current position pointer may be
     set and retrieved by <B><A HREF="lseek.html">lseek(2)</A></B>.  The current position pointer should only
     be set to a value returned by <B><A HREF="lseek.html">lseek(2)</A></B>,  a value returned in the location
     pointed to by <I>basep</I>, or zero.


</PRE>
<H2>IMPLEMENTATION NOTES</H2><PRE>
     In the non-threaded library <B>getdirentries</B>() is implemented as the
     <I>getdirentries</I> syscall.

     In the threaded library, the <I>getdirentries</I> syscall is assembled to
     <B>_thread_sys_getdirentries</B>() and <B>getdirentries</B>() is implemented as a func-
     tion which locks <I>fd</I> for read and write, then calls
     <B>_thread_sys_getdirentries</B>().  Before returning, <B>getdirentries</B>() unlocks
     <I>fd</I>.


</PRE>
<H2>RETURN VALUES</H2><PRE>
     If successful, the number of bytes actually transferred is returned.
     Otherwise, -1 is returned and the global variable <I>errno</I> is set to indi-
     cate the error.


</PRE>
<H2>ERRORS</H2><PRE>
     <B>Getdirentries</B>() will fail if:

     [EBADF]   <I>fd</I> is not a valid file descriptor open for reading.

     [EFAULT]  Either <I>buf</I> or <I>basep</I> point outside the allocated address space.

     [EINVAL]  The file referenced by <I>fd</I> is not a directory, or <I>nbytes</I> is too
	       small for returning a directory entry or block of entries, or
	       the current position pointer is invalid.

     [EIO]     An I/O error occurred while reading from or writing to the file
	       system.


</PRE>
<H2>SEE ALSO</H2><PRE>
     <B><A HREF="lseek.html">lseek(2)</A></B>,	<B><A HREF="open.html">open(2)</A></B>


</PRE>
<H2>HISTORY</H2><PRE>
     The <B>getdirentries</B>() function first appeared in 4.4BSD.

BSD				  May 3, 1995				     2
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
